home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / sgges.z / sgges
Encoding:
Text File  |  2002-10-03  |  9.9 KB  |  265 lines
  1.  
  2.  
  3.  
  4. SSSSGGGGGGGGEEEESSSS((((3333SSSS))))                                                            SSSSGGGGGGGGEEEESSSS((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      SGGES - compute for a pair of N-by-N real nonsymmetric matrices (A,B),
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      SUBROUTINE SGGES( JOBVSL, JOBVSR, SORT, SELCTG, N, A, LDA, B, LDB, SDIM,
  13.                        ALPHAR, ALPHAI, BETA, VSL, LDVSL, VSR, LDVSR, WORK,
  14.                        LWORK, BWORK, INFO )
  15.  
  16.          CHARACTER     JOBVSL, JOBVSR, SORT
  17.  
  18.          INTEGER       INFO, LDA, LDB, LDVSL, LDVSR, LWORK, N, SDIM
  19.  
  20.          LOGICAL       BWORK( * )
  21.  
  22.          REAL          A( LDA, * ), ALPHAI( * ), ALPHAR( * ), B( LDB, * ),
  23.                        BETA( * ), VSL( LDVSL, * ), VSR( LDVSR, * ), WORK( * )
  24.  
  25.          LOGICAL       SELCTG
  26.  
  27.          EXTERNAL      SELCTG
  28.  
  29. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  30.      These routines are part of the SCSL Scientific Library and can be loaded
  31.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  32.      directs the linker to use the multi-processor version of the library.
  33.  
  34.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  35.      4 bytes (32 bits). Another version of SCSL is available in which integers
  36.      are 8 bytes (64 bits).  This version allows the user access to larger
  37.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  38.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  39.      only one of the two versions; 4-byte integer and 8-byte integer library
  40.      calls cannot be mixed.
  41.  
  42. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  43.      SGGES computes for a pair of N-by-N real nonsymmetric matrices (A,B), the
  44.      generalized eigenvalues, the generalized real Schur form (S,T),
  45.      optionally, the left and/or right matrices of Schur vectors (VSL and
  46.      VSR). This gives the generalized Schur factorization
  47.  
  48.               (A,B) = ( (VSL)*S*(VSR)**T, (VSL)*T*(VSR)**T )
  49.  
  50.      Optionally, it also orders the eigenvalues so that a selected cluster of
  51.      eigenvalues appears in the leading diagonal blocks of the upper quasi-
  52.      triangular matrix S and the upper triangular matrix T.The leading columns
  53.      of VSL and VSR then form an orthonormal basis for the corresponding left
  54.      and right eigenspaces (deflating subspaces).
  55.  
  56.      (If only the generalized eigenvalues are needed, use the driver SGGEV
  57.      instead, which is faster.)
  58.  
  59.      A generalized eigenvalue for a pair of matrices (A,B) is a scalar w or a
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSGGGGGGGGEEEESSSS((((3333SSSS))))                                                            SSSSGGGGGGGGEEEESSSS((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      ratio alpha/beta = w, such that  A - w*B is singular.  It is usually
  75.      represented as the pair (alpha,beta), as there is a reasonable
  76.      interpretation for beta=0 or both being zero.
  77.  
  78.      A pair of matrices (S,T) is in generalized real Schur form if T is upper
  79.      triangular with non-negative diagonal and S is block upper triangular
  80.      with 1-by-1 and 2-by-2 blocks.  1-by-1 blocks correspond to real
  81.      generalized eigenvalues, while 2-by-2 blocks of S will be "standardized"
  82.      by making the corresponding elements of T have the form:
  83.              [  a  0  ]
  84.              [  0  b  ]
  85.  
  86.      and the pair of corresponding 2-by-2 blocks in S and T will have a
  87.      complex conjugate pair of generalized eigenvalues.
  88.  
  89.  
  90.  
  91. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  92.      JOBVSL  (input) CHARACTER*1
  93.              = 'N':  do not compute the left Schur vectors;
  94.              = 'V':  compute the left Schur vectors.
  95.  
  96.      JOBVSR  (input) CHARACTER*1
  97.              = 'N':  do not compute the right Schur vectors;
  98.              = 'V':  compute the right Schur vectors.
  99.  
  100.      SORT    (input) CHARACTER*1
  101.              Specifies whether or not to order the eigenvalues on the diagonal
  102.              of the generalized Schur form.  = 'N':  Eigenvalues are not
  103.              ordered;
  104.              = 'S':  Eigenvalues are ordered (see SELCTG);
  105.  
  106.      SELCTG  (input) LOGICAL FUNCTION of three REAL arguments
  107.              SELCTG must be declared EXTERNAL in the calling subroutine.  If
  108.              SORT = 'N', SELCTG is not referenced.  If SORT = 'S', SELCTG is
  109.              used to select eigenvalues to sort to the top left of the Schur
  110.              form.  An eigenvalue (ALPHAR(j)+ALPHAI(j))/BETA(j) is selected if
  111.              SELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) is true; i.e. if either one
  112.              of a complex conjugate pair of eigenvalues is selected, then both
  113.              complex eigenvalues are selected.
  114.  
  115.              Note that in the ill-conditioned case, a selected complex
  116.              eigenvalue may no longer satisfy SELCTG(ALPHAR(j),ALPHAI(j),
  117.              BETA(j)) = .TRUE. after ordering. INFO is to be set to N+2 in
  118.              this case.
  119.  
  120.      N       (input) INTEGER
  121.              The order of the matrices A, B, VSL, and VSR.  N >= 0.
  122.  
  123.      A       (input/output) REAL array, dimension (LDA, N)
  124.              On entry, the first of the pair of matrices.  On exit, A has been
  125.              overwritten by its generalized Schur form S.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSGGGGGGGGEEEESSSS((((3333SSSS))))                                                            SSSSGGGGGGGGEEEESSSS((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      LDA     (input) INTEGER
  141.              The leading dimension of A.  LDA >= max(1,N).
  142.  
  143.      B       (input/output) REAL array, dimension (LDB, N)
  144.              On entry, the second of the pair of matrices.  On exit, B has
  145.              been overwritten by its generalized Schur form T.
  146.  
  147.      LDB     (input) INTEGER
  148.              The leading dimension of B.  LDB >= max(1,N).
  149.  
  150.      SDIM    (output) INTEGER
  151.              If SORT = 'N', SDIM = 0.  If SORT = 'S', SDIM = number of
  152.              eigenvalues (after sorting) for which SELCTG is true.  (Complex
  153.              conjugate pairs for which SELCTG is true for either eigenvalue
  154.              count as 2.)
  155.  
  156.      ALPHAR  (output) REAL array, dimension (N)
  157.              ALPHAI  (output) REAL array, dimension (N) BETA    (output) REAL
  158.              array, dimension (N) On exit, (ALPHAR(j) + ALPHAI(j)*i)/BETA(j),
  159.              j=1,...,N, will be the generalized eigenvalues.  ALPHAR(j) +
  160.              ALPHAI(j)*i, and  BETA(j),j=1,...,N are the diagonals of the
  161.              complex Schur form (S,T) that would result if the 2-by-2 diagonal
  162.              blocks of the real Schur form of (A,B) were further reduced to
  163.              triangular form using 2-by-2 complex unitary transformations.  If
  164.              ALPHAI(j) is zero, then the j-th eigenvalue is real; if positive,
  165.              then the j-th and (j+1)-st eigenvalues are a complex conjugate
  166.              pair, with ALPHAI(j+1) negative.
  167.  
  168.              Note: the quotients ALPHAR(j)/BETA(j) and ALPHAI(j)/BETA(j) may
  169.              easily over- or underflow, and BETA(j) may even be zero.  Thus,
  170.              the user should avoid naively computing the ratio.  However,
  171.              ALPHAR and ALPHAI will be always less than and usually comparable
  172.              with norm(A) in magnitude, and BETA always less than and usually
  173.              comparable with norm(B).
  174.  
  175.      VSL     (output) REAL array, dimension (LDVSL,N)
  176.              If JOBVSL = 'V', VSL will contain the left Schur vectors.  Not
  177.              referenced if JOBVSL = 'N'.
  178.  
  179.      LDVSL   (input) INTEGER
  180.              The leading dimension of the matrix VSL. LDVSL >=1, and if JOBVSL
  181.              = 'V', LDVSL >= N.
  182.  
  183.      VSR     (output) REAL array, dimension (LDVSR,N)
  184.              If JOBVSR = 'V', VSR will contain the right Schur vectors.  Not
  185.              referenced if JOBVSR = 'N'.
  186.  
  187.      LDVSR   (input) INTEGER
  188.              The leading dimension of the matrix VSR. LDVSR >= 1, and if
  189.              JOBVSR = 'V', LDVSR >= N.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSGGGGGGGGEEEESSSS((((3333SSSS))))                                                            SSSSGGGGGGGGEEEESSSS((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      WORK    (workspace/output) REAL array, dimension (LWORK)
  207.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  208.  
  209.      LWORK   (input) INTEGER
  210.              The dimension of the array WORK.  LWORK >= 8*N+16.
  211.  
  212.              If LWORK = -1, then a workspace query is assumed; the routine
  213.              only calculates the optimal size of the WORK array, returns this
  214.              value as the first entry of the WORK array, and no error message
  215.              related to LWORK is issued by XERBLA.
  216.  
  217.      BWORK   (workspace) LOGICAL array, dimension (N)
  218.              Not referenced if SORT = 'N'.
  219.  
  220.      INFO    (output) INTEGER
  221.              = 0:  successful exit
  222.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  223.              = 1,...,N:  The QZ iteration failed.  (A,B) are not in Schur
  224.              form, but ALPHAR(j), ALPHAI(j), and BETA(j) should be correct for
  225.              j=INFO+1,...,N.  > N:  =N+1: other than QZ iteration failed in
  226.              SHGEQZ.
  227.              =N+2: after reordering, roundoff changed values of some complex
  228.              eigenvalues so that leading eigenvalues in the Generalized Schur
  229.              form no longer satisfy SELCTG=.TRUE.  This could also be caused
  230.              due to scaling.  =N+3: reordering failed in STGSEN.
  231.  
  232. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  233.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  234.  
  235.      This man page is available only online.
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.